Frontend Integration Architecture

**Referenced Files in This Document** - [main.js](file://src/assets/js/main.js) - [base.njk](file://src/_includes/layouts/base.njk) - [main.css](file://src/assets/css/main.css) - [navigation.js](file://src/assets/js/modules/navigation.js) - [carousel-system.js](file://src/assets/js/modules/carousel-system.js) - [theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [search-functionality.js](file://src/assets/js/modules/search-functionality.js) - [material-design-3-main-theme-toggle.js](file://src/assets/js/modules/material-design-3-main-theme-toggle.js) - [04-navigation.css](file://src/assets/css/modules/04-navigation.css) - [25-responsive-tablet-max-width-1024px.css](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css) - [26-responsive-mobile-max-width-900px.css](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css) - [38-material-design-3-theme-toggle.css](file://src/assets/css/modules/38-material-design-3-theme-toggle.css) - [41-search-modal.css](file://src/assets/css/modules/41-search-modal.css) - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document describes the frontend integration architecture that connects Eleventy’s static generation pipeline with interactive JavaScript components. It explains the modular JavaScript architecture with 14 distinct modules, the CSS architecture with 44 modular stylesheets organized by functionality and responsive breakpoints, and the integration between Nunjucks templates and JavaScript. It also details the progressive enhancement strategy, the theme system supporting Material Design 3 and light/dark mode, and the asset loading strategy with performance optimizations.

Project Structure

The frontend is organized around a static site generator (Eleventy) that compiles Nunjucks templates and data into HTML, while a modular JavaScript entry point initializes interactive features. Styles are composed from 44 CSS modules imported into a single main stylesheet. The base template wires everything together, including third-party libraries and modulepreload hints.

graph TB
subgraph "Build & Template Layer"
ELE[".eleventy.js<br/>Passthrough copy, filters, transforms"]
NJK["Nunjucks Templates<br/>(layouts, includes)"]
end
subgraph "Static Assets"
CSS_MAIN["main.css<br/>Imports 44 modules"]
JS_MAIN["main.js<br/>Imports 14 modules"]
end
subgraph "Runtime"
BASE["base.njk<br/>HTML shell, scripts, markup"]
GSAP["CDN GSAP + ScrollTrigger"]
PF["Pagefind Module"]
end
ELE --> NJK
NJK --> BASE
CSS_MAIN --> BASE
JS_MAIN --> BASE
GSAP --> BASE
PF --> BASE

Diagram sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Core Components

  • Modular JavaScript entry point initializes 14 modules on DOMContentLoaded, conditionally enabling advanced animations when GSAP is available.
  • CSS composition via main.css imports 44 functional modules plus responsive breakpoints.
  • Nunjucks base layout provides markup for navigation, search modal, and theme toggle, wired to JavaScript modules.
  • Progressive enhancement ensures core functionality remains usable without JavaScript, with enhancements layered on top.

Section sources

  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)
  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)

Architecture Overview

The runtime architecture follows a layered approach:

  • Build-time: Eleventy copies assets and builds templates with filters and transforms.
  • Delivery-time: The base template loads fonts, main CSS, optional Three.js for the home hero, and the main JavaScript bundle.
  • Runtime: The JavaScript entry initializes modules, progressively enhancing the UI with interactivity and animations.
sequenceDiagram
participant Browser as "Browser"
participant Layout as "base.njk"
participant CSS as "main.css"
participant JS as "main.js"
participant Modules as "14 Modules"
Browser->>Layout : Request HTML
Layout-->>Browser : HTML with links to CSS/JS
Browser->>CSS : Load main.css
Browser->>JS : Load main.js (type=module)
JS->>Modules : Initialize modules
Modules-->>Browser : Interactive UI enhancements
Note over Browser,Modules : Core features work without JS; JS enhances UX

Diagram sources

  • [base.njk:27-258](file://src/_includes/layouts/base.njk#L27-L258)
  • [main.js:15-36](file://src/assets/js/main.js#L15-L36)

Section sources

  • [base.njk:27-258](file://src/_includes/layouts/base.njk#L27-L258)
  • [main.js:15-36](file://src/assets/js/main.js#L15-L36)

Detailed Component Analysis

JavaScript Initialization Pattern

The entry point imports and invokes 14 modules during DOMContentLoaded. It conditionally registers GSAP ScrollTrigger and enables custom cursor and hero animations only when external libraries are present.

flowchart TD
Start(["DOMContentLoaded"]) --> InitNav["initNavigation()"]
InitNav --> InitTheme["initThemeToggling()"]
InitTheme --> InitTeam["initTeamCardFlip()"]
InitTeam --> InitCarousels["initCarousels()"]
InitCarousels --> InitAccordion["initAccordion()"]
InitAccordion --> InitScrollPolish["initScrollPolish()"]
InitScrollPolish --> InitPoll["initPollAnimation()"]
InitPoll --> InitMainTheme["initThemeToggle()"]
InitMainTheme --> InitSearch["initSearch()"]
InitSearch --> InitIAATheme["initIAAThemeToggle()"]
InitIAATheme --> InitNewsletter["initNewsletterSpamProtection()"]
InitNewsletter --> CheckGSAP{"GSAP available?"}
CheckGSAP --> |Yes| GSAPInit["Register ScrollTrigger<br/>initCustomCursor()<br/>initHeroAnimations()"]
CheckGSAP --> |No| Warn["Log warning, core features active"]

Diagram sources

  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Section sources

  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Navigation Module

Responsibilities:

  • Toggle mobile menu with accessibility support (focus trapping, Escape handling).
  • Close menu on click outside and on link selection.
  • Manage ARIA attributes and keyboard navigation.
sequenceDiagram
participant U as "User"
participant Nav as "Navigation Module"
participant DOM as "DOM"
U->>Nav : Click hamburger
Nav->>DOM : Add/remove active classes
Nav->>DOM : Toggle aria-expanded
U->>Nav : Press Escape
Nav->>DOM : Close menu
U->>Nav : Click nav link
Nav->>DOM : Close menu
U->>Nav : Click outside
Nav->>DOM : Close menu

Diagram sources

  • [navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)

Section sources

  • [navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)

Carousel System Module

Responsibilities:

  • Configure multiple carousels (capabilities, testimonials, news) with dynamic pagination dots.
  • Calculate scroll amounts per viewport width and gap.
  • Keyboard navigation, drag-to-scroll, and responsive updates on resize.
  • Accessibility: roles, labels, and ARIA descriptions.
flowchart TD
Init["Initialize Carousels"] --> Setup["setupCarousel(config)"]
Setup --> Find["Find viewport and track"]
Find --> RenderDots["renderDots(): compute snap points"]
RenderDots --> Bind["Bind prev/next and keyboard events"]
Bind --> Drag["Enable drag-to-scroll"]
Drag --> Resize["Listen to resize and re-render dots"]
Resize --> State["updateState(): manage opacity and active dots"]

Diagram sources

  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)

Section sources

  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)

Search Functionality Module

Responsibilities:

  • Lazy-load Pagefind on demand.
  • Open/close modal, handle input with debounced search.
  • Render categorized results with icons and excerpts.
  • Keyboard navigation (arrow keys, Enter, Escape).
  • Support global shortcut to open modal.
sequenceDiagram
participant U as "User"
participant Search as "Search Module"
participant PF as "Pagefind"
U->>Search : Click search toggle
Search->>Search : Open modal, focus input
U->>Search : Type query (debounced)
Search->>PF : Search(query)
PF-->>Search : Results
Search->>Search : Render results with categories
U->>Search : Arrow up/down, Enter, Escape
Search->>Search : Update selection, navigate or close

Diagram sources

  • [search-functionality.js:1-179](file://src/assets/js/modules/search-functionality.js#L1-L179)

Section sources

  • [search-functionality.js:1-179](file://src/assets/js/modules/search-functionality.js#L1-L179)

Theme Toggling Module

Responsibilities:

  • Switch between light and dark themes globally.
  • Persist preference in localStorage.
  • Update ARIA state and body classes for theme-aware components.
sequenceDiagram
participant U as "User"
participant Theme as "Theme Toggle Module"
participant Storage as "localStorage"
U->>Theme : Click theme toggle
Theme->>Theme : Determine new theme
Theme->>Storage : Save preference
Theme->>Theme : Update body classes and aria-checked

Diagram sources

  • [material-design-3-main-theme-toggle.js:1-38](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L1-L38)

Section sources

  • [material-design-3-main-theme-toggle.js:1-38](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L1-L38)

CSS Architecture and Responsive Breakpoints

The CSS architecture is modular and layered:

  • main.css imports 44 functional modules covering navigation, carousels, forms, footers, and page-specific styles.
  • Responsive breakpoints are defined in dedicated modules for tablet (≤1024px), mobile (≤900px), small mobile (≤600px), and extra-small (≤480px).
  • Material Design 3 theming variables and the theme toggle UI are defined in separate modules.
graph LR
M["main.css"] --> N["04-navigation.css"]
M --> C1["09-services-carousel-homepage.css"]
M --> C2["11-testimonials-carousel.css"]
M --> C3["13-news-carousel-homepage.css"]
M --> F["16-contact-form.css"]
M --> T["17-footer.css"]
M --> R1024["25-responsive-tablet-max-width-1024px.css"]
M --> R900["26-responsive-mobile-max-width-900px.css"]
M --> R600["27-responsive-small-mobile-max-width-600px.css"]
M --> R480["28-responsive-extra-small-max-width-480px.css"]
M --> MD["38-material-design-3-theme-toggle.css"]
M --> S["41-search-modal.css"]

Diagram sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [04-navigation.css:1-101](file://src/assets/css/modules/04-navigation.css#L1-L101)
  • [25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
  • [26-responsive-mobile-max-width-900px.css:1-358](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L1-L358)
  • [38-material-design-3-theme-toggle.css:1-237](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L1-L237)
  • [41-search-modal.css:1-314](file://src/assets/css/modules/41-search-modal.css#L1-L314)

Section sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [04-navigation.css:1-101](file://src/assets/css/modules/04-navigation.css#L1-L101)
  • [25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
  • [26-responsive-mobile-max-width-900px.css:1-358](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L1-L358)
  • [38-material-design-3-theme-toggle.css:1-237](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L1-L237)
  • [41-search-modal.css:1-314](file://src/assets/css/modules/41-search-modal.css#L1-L314)

Integration Between Nunjucks and JavaScript

  • The base template defines the navigation markup, search modal, and theme toggle HTML and ARIA attributes.
  • JavaScript modules attach event listeners and manipulate classes and attributes based on user interactions.
  • Data passing occurs via DOM attributes (e.g., data-theme) and local storage preferences.
sequenceDiagram
participant Template as "base.njk"
participant JS as "main.js"
participant Module as "Module"
participant DOM as "DOM"
Template-->>DOM : Render markup (nav, search, theme toggle)
JS->>DOM : Select elements by class/id
JS->>Module : Call initXXX()
Module->>DOM : Add event listeners, set ARIA, update classes

Diagram sources

  • [base.njk:67-256](file://src/_includes/layouts/base.njk#L67-L256)
  • [main.js:15-36](file://src/assets/js/main.js#L15-L36)

Section sources

  • [base.njk:67-256](file://src/_includes/layouts/base.njk#L67-L256)
  • [main.js:15-36](file://src/assets/js/main.js#L15-L36)

Progressive Enhancement Strategy

  • Core navigation and content remain functional without JavaScript.
  • JavaScript enhances with animated mobile menu, carousels, search, and theme switching.
  • Animations (GSAP) are optional; absence of GSAP logs a warning and degrades gracefully while keeping core features active.

Section sources

  • [main.js:28-35](file://src/assets/js/main.js#L28-L35)
  • [base.njk:63-256](file://src/_includes/layouts/base.njk#L63-L256)

Component Library System and Reusable Macros

  • The project uses Nunjucks macros under includes/macros for reusable UI components (e.g., cards, CTAs, testimonials).
  • These macros are integrated into content pages and layouts, promoting consistency and reducing duplication.
  • While not part of the JavaScript modules, they complement the modular CSS and JS architecture by providing structured, reusable markup.

Section sources

  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)

Responsive Design Architecture (Mobile-First)

  • Breakpoints are organized into four CSS modules: tablet (≤1024px), mobile (≤900px), small mobile (≤600px), and extra-small (≤480px).
  • The navigation adapts from desktop links to a full-screen animated mobile menu with staggered entrance effects.
  • Carousels adjust card widths and scroll behavior per breakpoint, ensuring usability on all devices.

Section sources

  • [25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
  • [26-responsive-mobile-max-width-900px.css:1-358](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L1-L358)
  • [04-navigation.css:1-101](file://src/assets/css/modules/04-navigation.css#L1-L101)

Theme System Architecture (Material Design 3 + Light/Dark)

  • Material Design 3 color tokens are mapped to CSS custom properties in the theme toggle module.
  • The theme toggle persists user preference and updates body classes for light/dark variants.
  • The base template initializes the body with a default theme class and integrates the theme toggle UI in the footer.
flowchart TD
Root[":root<br/>MD3 color tokens"] --> Light["body.theme-light<br/>light palette"]
Root --> Dark["body.theme-dark<br/>dark palette"]
Toggle["Theme Toggle UI"] --> Light
Toggle --> Dark
Storage["localStorage"] --> Toggle

Diagram sources

  • [38-material-design-3-theme-toggle.css:6-33](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L6-L33)
  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [base.njk:63](file://src/_includes/layouts/base.njk#L63)

Section sources

  • [38-material-design-3-theme-toggle.css:6-33](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L6-L33)
  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [base.njk:63](file://src/_includes/layouts/base.njk#L63)

Asset Loading Strategy and Performance Optimizations

  • Eleventy passes through assets and watches CSS/JS/data directories for development.
  • Fonts are preconnected and loaded with deferred media to avoid render-blocking.
  • GSAP is loaded from CDN and ScrollTrigger conditionally on non-home pages; Three.js is modulepreloaded only on the home page.
  • Pagefind is dynamically imported for search, minimizing initial bundle size.
  • HTML minification runs in production to reduce payload.
graph TB
ELE[".eleventy.js<br/>Passthrough copy, watch targets"] --> Build["_site output"]
Fonts["Preconnect fonts + deferred media"] --> Build
GSAP["CDN GSAP + ScrollTrigger"] --> Build
Three["modulepreload three.module.js"] --> Build
PF["Dynamic import pagefind.js"] --> Build
Minify["HTML minify in production"] --> Build

Diagram sources

  • [.eleventy.js:7-22](file://.eleventy.js#L7-L22)
  • [base.njk:21-30](file://src/_includes/layouts/base.njk#L21-L30)
  • [package.json:5-12](file://package.json#L5-L12)

Section sources

  • [.eleventy.js:7-22](file://.eleventy.js#L7-L22)
  • [base.njk:21-30](file://src/_includes/layouts/base.njk#L21-L30)
  • [package.json:5-12](file://package.json#L5-L12)

Dependency Analysis

  • The JavaScript entry depends on 14 modules, each encapsulating a specific UI feature.
  • CSS depends on 44 modules and responsive breakpoint modules.
  • The base template depends on the main CSS and main JS bundles, and optionally on external libraries.
graph LR
JSMAIN["main.js"] --> NAV["navigation.js"]
JSMAIN --> THEME["theme-toggling.js"]
JSMAIN --> CURSOR["custom-cursor.js"]
JSMAIN --> HERO["hero-animations.js"]
JSMAIN --> SCROLL["scroll-nav-polish.js"]
JSMAIN --> CAROUSEL["carousel-system.js"]
JSMAIN --> TEAM["team-card-flip.js"]
JSMAIN --> ACCORD["accordion.js"]
JSMAIN --> POLL["poll-bar-animation.js"]
JSMAIN --> MDMAIN["material-design-3-main-theme-toggle.js"]
JSMAIN --> IAA["iaa-alliance-theme-toggle.js"]
JSMAIN --> SEARCH["search-functionality.js"]
JSMAIN --> NEWS["newsletter-spam-protection.js"]
CSSMAIN["main.css"] --> MODS["44 CSS modules"]
CSSMAIN --> RESP["Responsive modules"]

Diagram sources

  • [main.js:1-14](file://src/assets/js/main.js#L1-L14)
  • [main.css:3-46](file://src/assets/css/main.css#L3-L46)

Section sources

  • [main.js:1-14](file://src/assets/js/main.js#L1-L14)
  • [main.css:3-46](file://src/assets/css/main.css#L3-L46)

Performance Considerations

  • Defer non-critical scripts and lazy-load heavy libraries (GSAP, Pagefind).
  • Use modulepreload for critical third-party modules on specific pages.
  • Minify HTML in production to reduce transfer size.
  • Keep CSS modular to enable selective loading and maintainability.
  • Avoid layout thrashing by batching DOM reads/writes and using passive event listeners.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • If animations do not play, check that GSAP is loaded and ScrollTrigger is registered; the entry logs a warning when missing.
  • If search does not work, verify Pagefind is built and imported; the module handles unavailability gracefully.
  • If mobile menu does not open, confirm the presence of the toggle and menu elements and that the module is initialized.
  • If theme toggle does not persist, ensure localStorage is enabled and the module updates ARIA attributes correctly.

Section sources

  • [main.js:28-35](file://src/assets/js/main.js#L28-L35)
  • [search-functionality.js:18-28](file://src/assets/js/modules/search-functionality.js#L18-L28)
  • [navigation.js:3-75](file://src/assets/js/modules/navigation.js#L3-L75)
  • [material-design-3-main-theme-toggle.js:10-27](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L10-L27)

Conclusion

The frontend integration system combines a clean modular JavaScript architecture with a highly organized CSS foundation and robust Nunjucks templating. Progressive enhancement ensures accessibility and performance across devices, while the Material Design 3 theme system provides a cohesive light/dark experience. The asset loading strategy and Eleventy configuration optimize delivery and developer productivity.